Add example whatsnew file #2418
Conversation
There was a problem hiding this comment.
Good catch, this is a nice improvement IMO.
I think we could merge Testing and Benchmarking into Maintenance, (maybe rename to Development or a broader concept), since they don't really impact users (benchmarking means changes to asv benchmarks, right? I assume it's not about speed improvements in algorithms, that should probably go into Enhancements).
And on the other hand, Requirements section is similar to Breaking Changes. For example, bumping python or numpy versions.
| @@ -0,0 +1,45 @@ | |||
| .. _whatsnew_0XXYY: | |||
There was a problem hiding this comment.
| .. _whatsnew_0XXYY: | |
| .. _whatsnew_0_X_Y: |
This is just personal taste, IK it's not the legacy form, but easier to read.
There was a problem hiding this comment.
I also prefer underscores. But what is the purpose of this tag and where does it show up (it at all)?
There was a problem hiding this comment.
This is the hyperlink target, you would use it in rST like :ref:`whatsnew_0_X_Y`
Benchmarking indeed does refer to ASV. I would be fine with merging benchmarking and testing and naming it "Development".
Still open to other ideas! |
|
I disagree with lumping Testing and Benchmarking into Development. Testing is a useful category of change on its own. Development is a broad term that I think of as adding content. |
|
Could we revisit this idea? Adding |
Hmm... I did not find a full docs page (did I miss something?) but there's a short explanation in the 0.2 release and I see it used in several pvlib files, e.g. |
|
@AdamRJensen @RDaxini this is the In any case, I'm slightly opposed to using it, cause I find it clearer to state whether the references are about something inside pvlib or outside (remember there is intersphinx enabled for packages like numpy, scipy or pandas) |
Part of pvlib's release procedures is to add a new empty Whatsnew file after the release of a new version.
I believe the current practice is to take the previous whatsnew file and delete the content. This is tedious. More of a problem is that not all releases include all types of contributions and thus the added whatsnew file is often missing sections. While, these sections typically get added, they tend to get added in a random order (maybe not a big deal).
In any case, to make the release procedure smoother I suggest having a Whatsnew template that we use as the bases for the new Whatsnew file that is added after a release. The example Whatsnew file has all possible sections (at least the ones we've used historically). Please comment if you think more should be added, if some are obsolete, or if you think that they should be ordered differently.